/**
 * 前端API接口文档配置文件
 * 
 * 这个文件提供了前端应用中使用的API接口的详细说明和类型定义
 * 可以用于生成API文档或提供IDE智能提示
 */

/**
 * @typedef {Object} User
 * @property {number} id - 用户ID
 * @property {string} username - 用户名
 * @property {string} email - 用户邮箱
 * @property {string} avatar - 用户头像URL
 * @property {string} [role='user'] - 用户角色，默认为'user'
 */

/**
 * @typedef {Object} ChatMessage
 * @property {string} type - 消息类型，'user'或'ai'
 * @property {string} content - 消息内容
 * @property {Date} timestamp - 消息时间戳
 * @property {Object} [file] - 可选的文件信息
 * @property {string} [file.fileUrl] - 文件URL
 * @property {string} [file.fileType] - 文件类型，'image'或'audio'
 * @property {string} [file.fileName] - 文件名称
 * @property {string} [file.localUrl] - 本地文件URL
 */

/**
 * @typedef {Object} AIResponse
 * @property {boolean} success - 请求是否成功
 * @property {Object} data - 返回的数据
 * @property {string} data.message - AI回复的消息
 * @property {string} [message] - 错误信息（如果有）
 */

/**
 * @typedef {Object} ChatHistoryResponse
 * @property {boolean} success - 请求是否成功
 * @property {Array<Object>} data - 聊天历史记录
 * @property {number} data[].id - 消息ID
 * @property {string} data[].role - 消息角色，'user'或'ai'
 * @property {string} data[].content - 消息内容
 * @property {string} [data[].file_url] - 文件URL（如果有）
 * @property {string} [data[].file_type] - 文件类型（如果有）
 * @property {string} data[].created_at - 创建时间
 */

/**
 * @typedef {Object} StoryResponse
 * @property {boolean} success - 请求是否成功
 * @property {string} story - 生成的故事内容
 * @property {string} [error] - 错误信息（如果有）
 */

/**
 * @typedef {Object} UploadResponse
 * @property {boolean} success - 上传是否成功
 * @property {string} fileUrl - 上传后的文件URL
 * @property {string} fileName - 文件名
 * @property {string} [error] - 错误信息（如果有）
 */

/**
 * AI聊天API
 * @namespace AIChat
 */

/**
 * 发送消息给AI
 * 
 * @function
 * @memberof AIChat
 * @name sendMessage
 * @param {Object} payload - 请求参数
 * @param {string} payload.message - 消息内容
 * @param {string} [payload.fileUrl] - 文件URL（如果有）
 * @param {string} [payload.fileType] - 文件类型（如果有）
 * @returns {Promise<AIResponse>} AI回复
 * 
 * @example
 * // 发送纯文本消息
 * const response = await sendMessage({ message: '你好' });
 * 
 * // 发送带图片的消息
 * const response = await sendMessage({
 *   message: '这是一张图片',
 *   fileUrl: 'https://example.com/image.jpg',
 *   fileType: 'image'
 * });
 */

/**
 * 获取聊天历史
 * 
 * @function
 * @memberof AIChat
 * @name getChatHistory
 * @returns {Promise<ChatHistoryResponse>} 聊天历史记录
 * 
 * @example
 * const history = await getChatHistory();
 * console.log(history.data); // 聊天记录数组
 */

/**
 * 生成故事
 * 
 * @function
 * @memberof AIChat
 * @name generateStory
 * @param {Object} payload - 请求参数
 * @param {string} payload.prompt - 故事生成提示
 * @returns {Promise<StoryResponse>} 生成的故事
 * 
 * @example
 * const result = await generateStory({
 *   prompt: '请生成一个关于小狗历险记的短故事'
 * });
 * console.log(result.story); // 生成的故事内容
 */

/**
 * 上传文件
 * 
 * @function
 * @memberof AIChat
 * @name uploadFile
 * @param {File} file - 要上传的文件对象
 * @returns {Promise<UploadResponse>} 上传结果
 * 
 * @example
 * const fileInput = document.querySelector('input[type="file"]');
 * const file = fileInput.files[0];
 * const result = await uploadFile(file);
 * console.log(result.fileUrl); // 上传后的文件URL
 */

export default {
  version: '1.0.0',
  baseUrl: '/api',
  endpoints: {
    chat: '/ai/chat',
    history: '/ai/history',
    generateStory: '/ai/generate-story',
    uploadFile: '/upload'
  }
}; 